Tutorial 5 adds new functions, Bubble Help, an arexx host, tooltypes and commodity. Although they are advanced features by now it should be easy for you to follow the logic. They work in very similar ways to the other objects you have learned to deal with. Adding these sort of features to your own GUI's will help make them Quality programs.
Before reading this section take a moment and run tutorial 5, knowing what the GUI does will help in understanding the code behind it.
Tutorial 5 is only available in Arexx for now, the discussion is kept general and it applies to both 'C' and ARexx.
TUTORIAL 5
-----------
Most users only scan documentation at best. To allow users to quickly understand your programs Bubble help is very useful.
A few simple changes are made in the window definition. It now tells the GUI to send help and window activation events.This is done by adding 'help' and 'state' keywords.
A menu option has been added to turn the help bubbles on or off.
A change has been made in the main loop, we send 'tick 50' rather than continue when we want to get an event from the pipe. Like continue this ends the modify command part of the conversation and tells the GUI to send us an event. It also forces the GUI to send us a 'tick' event after 50/100 of a second. We use these tick events to delay the displaying of help bubbles.
Tick events have other uses, like returning control back to your code after a set delay so it does not wait forever for an event. For now we will just look at the help delay.
Each time an event is read in the main loop we check a delay counter. If the counter counts down to 0 we open a help bubble (using some previously stored information). The HELPX and HELPY are used to determine a position for the bubble and MUST be given.
'bubble top HELPX left HELPY gt "HELP TEXT"'
We also must handle new events, help, arexx, cx and active.
We respond to the help event by calling the bubble routine. This routine checks to see if the help event is the same as the last one. If yes we do nothing. If it changed we close the old help window, if we had one, by sending a bubble modify command with no parameters.
'bubble'
If the event was gadget 0 or -1 we have nothing more to do since they represent the mouse not being over a valid gadget. If the gadget number is valid we store the mouse position that is returned in the help event and the gadget number. We start the delay counter and return.
If we receive any activation event, or iconify the gui, we call bubble(0) to close any open bubble help. This needed in case our window becomes inactive due to another window being opened.
An arexx host has been added to the GUI. The ARexx host name is 'TUTORIAL5'. This allows a few things.
If upon startup the host already exists we know tutorial 5 is already running so the already running gui and brought to front rather than a second occurrence of tutorial 5 being opened.
It supports a hotkey (ctrl alt 5), show or hide the gui, and remove. Enable/disable are ignored as they make no sense in the context of Tutorial 5 ...
(See the commodity: routine)
TOOLTYPES
Tooltype reading is actually not part of the AWNPipe GUI host, its a completely different host inside AWNPipe. Since tooltypes are desirable for almost all programs it has been added to this tutorial. You find the function simple to use.
Reading tooltypes
The tooltypes are read by a function called tooltypes:. First the path to our program is found using 'parse source'. Then a special pipe is opened 'awnpipe:name/xtPATH:PROGRAM'. A line containing the tooltype we wish to check is written to this pipe. If the tool type is found we will read back from the pipe 'ok VALUE' where VALUE is the value associated with the tool type we asked for. If the tooltype is not found we read back a <cr> (empty line).
When all the tooltypes have been checked we simply close the pipe connection to the tooltype host.
In tutorial5 the windows size/position and bubble help setting are now kept as a tooltype.
There are also tooltypes to preset the age, knowledge, sex and name. You can force the window to iconify after opening with the iconify tooltype.
Writing tooltypes
The tooltypes are written by a function called settooltypes:. It is called when the user selects one of the snapshot options. First we read the existing icon information and remove the window tooltype if there is one. Then we write the information back to the icon adding a new window tooltype if appropriate.
